Back to Main Menu

Retrieve Assets and associated records

Introduction

The Assetic REST Asset APIs can be used to retrieve asset detail on a per asset basis or as a paginated list of assets.  These APIs are intended for use in integration processes and not for bulk data extracts, for which the Using Advanced Search to bulk export process is more appropriate.

 

Please read the article Asset Integration Overview if unclear how these endpoints relate to the asset structure in Assetic

 

There is a rate limit applied to the Assetic REST API which should be considered when attempting to create a large number of records.

API endpoints

The following Assetic REST API endpoints are available for retrieving asset detail:

  • GET /api/v2/assets/{id}
      • Retrieve a single asset record using a user-friendly Asset ID or the unique system asset GUID.
  • GET /api/v2/assets
      • Retrieve a paginated collection of assets based on a search filter
  • GET /api/v2/assets/locations
  • GET /api/v2/assets/{id}/location
      • Retrieve a specific asset's spatial and physical location information using the unique system asset GUID.
  • GET /api/v2/components/{id}
      • Retrieve a component using the user-friendly Component ID or the unique system component GUID.
  • GET /api/v2/components
      • Retrieve a paginated list of components based on a search filter
  • GET /api/v2/components/{id}/dimensions
      • Retrieve a paginated collection of dimensions for a component.  The user-friendly Component ID or the unique system component GUID may be used.
  • GET /api/v2/dimensions
      • Retrieve a paginated collection of dimensions based on a search filter
  • GET /api/v2/functionallocations/{id}
      • Get a functional location using either the user-friendly Functional Location ID or the Assetic internal GUID for the functional location.
  • GET /api/v2/functionallocation
      • Retrieve a paginated collection of functional locations based on a search filter
  • GET /api/v2/servicecriteria/score
      • Retrieve a list of service criteria scores based on a search filter
  • GET /api/v2/servicecriteria/score/{id}
      • Retrieve a service criteria record for the given scored Id

Filtering and sorting

For the Assetic REST API endpoints GET /api/v2/assets and GET /api/v2/components the results may be filtered and sorted by the core asset/component fields.  For more details refer to Search Filters and Pagination

 

Asset Attribute fields may not be included in a search filter, or for sort order.  To apply a search filter or sort order to an attribute field use the Advanced Search API or OData endpoint instead.

Define a list of records to retrieve via 'in' parameter

The API GET /api/v2/assets has an additional search parameter option that allows a list of values to be used by an 'in' filter.  This allows each value in the list to be evaluated independently of any other value in the list and is useful for getting a list of assets where the Asset Id is known.  Multiple lists may be applied, each list will be an 'AND'

 

In the example below the search returns a set of assets from a list provided the assets are also from one of the Asset Categories in the second list.

https://xxx.assetic.net/api/v2/assets/?requestParams.in=AssetId='ABAB','CDAB','EFAB','ABAW'
&requestParams.in=AssetCategory='Artworks','Airport Buildings','Bridges'
Note: The 'in' parameter is only supported by the GET /api/v2/assets API

Pagination

For the Assetic REST API endpoints with paginated results, there is a 500 records per page maximum and a 20 record default. Unlike the Advanced Search API, there is no limit to the number of pages that may be returned.

 

The 'pageSize' parameter is used to set page size, and the 'page' parameter is used to set the page number.

 

GET /api/v2/assets/{id} and GET /api/v2/assets

The API GET /api/v2/assets/{id} accepts either the user-friendly Asset ID string or the internal Assetic GUID for the asset as the {id}

Attributes

The Assetic REST API's GET /api/v2/assets/{id} and GET /api/v2/assets return a small set of core asset fields.  Additional attribute fields may be specified as a list as part of the GET request.  An 'attribute' field is any of the fields that are in the pages contained within the 'Attributes' dropdown list in the Assetic application.

 
Note: 'calculated' fields are not available in the GET request or response.  To obtain calculated fields the Advanced Search API should be used instead.

 

To obtain a list of the asset attribute field names to include in the GET request, use the Advanced Search Metadata API to get the 'field name' (not 'label').  To use this API first create an advanced search with the attribute fields that you require field names for.  Save the profile and then use that profile in Advanced Search Metadata API requests.

 

Attribute fields are optionally included via the 'attributes' parameter. They can be supplied as a comma-separated list.

 
Note: The apidocs page requires at least one attribute to be defined for the endpoints GET /api/v2/assets/{id} and GET /api/v2/assets, but this is not the case if not testing the APIs via this page.

Core Asset Fields

The core asset fields that are always returned by the Asset APIs are listed in the article Asset Integration Overview

Sample Payload

The following request retrieves an asset using the user-friendly asset ID "A101".
The 'Zone' attribute is also specified for return by the response

https://xxx.assetic.net/api/v2/assets/A101?attributes=Zone

The following request retrieves an asset using the system GUID for the asset.  In this example, there are no additional attributes requested.

https://xxx.assetic.net/api/v2/assets/3c726e2d-ab4f-e611-9465-06edd62954e7

The following request retrieves a paginated list of assets including the attribute fields 'Zone' and 'Comment'

https://xxx.assetic.net/api/v2/assets?attributes=Zone,Comment

The default page size is 20, and the first page is returned.

GET /api/v2/assets/{id}/location

The Assetic REST API endpoint GET /api/v2/assets/{id}/location retrieves an asset's spatial information in GeoJSON format, using the unique system asset GUID. The "properties" of the response contains an "AssetPhysicalLocation" object which details the asset's physical location.

 

If an asset's GUID is unknown, the endpoint GET /api/v2/assets may be used with a search filter to first retrieve a sub-set list of assets, as documented in the above section of this same article.

 

Additional information on the GeoJSON format and specification can be found on the official website here.

Sample Payload

The following request retrieves an asset's spatial information using the system GUID for the asset:

https://xxx.assetic.net/api/v2/assets/3c726e2d-ab4f-e611-9465-06edd62954e7/location

 

GET /api/v2/components/{id} and GET /api/v2/components

The Assetic REST API endpoint GET /api/v2/components/{id} retrieves a single component given the user-visible Component ID or the unique system component GUID.

 

If the component ID and GUID are unknown, the endpoint GET /api/v2/components may be used with a search filter to get a list of components.  The list of searchable fields for components is defined in the article Asset Integration Overview.

Sample Payloads

Get the component details for the component ID "CP00394805" 

GET /api/v2/components/CP00394805

Alternatively the Component GUID "8a439a40-6e1e-e711-946c-06edd62954d7" may be used to get the component

GET /api/v2/components/8a439a40-6e1e-e711-946c-06edd62954d7

Get the paginated list of components for asset "A101" using the search filter for the endpoint GET /api/v2/components.  The results are sorted by component name in descending order.

GET /api/v2/components requestParams.pageSize=500&requestParams.page=1 &requestParams.filters=AssetId='A101' requestParams.sorts=Name-desc

GET /api/v2/components/{id}/dimensions and GET /api/v2/dimensions

A paginated list of dimensions within a component is obtained via the Assetic REST API endpoint GET /api/v2/components/{id}/dimensions.  The user-friendly Component ID or the unique system component GUID may be used.

 

The endpoint GET /api/v2/components may be used with a search filter to get a list of dimensions across one or more components.

Sample Payloads

Get the dimension details for the component ID "CP00394805" 

GET /api/v2/components/CP00394805/dimensions

Alternatively the Component GUID "8a439a40-6e1e-e711-946c-06edd62954d7" may be used to get the component dimensions

GET /api/v2/components/8a439a40-6e1e-e711-946c-06edd62954d7/dimensions

For the 'Roads' get category get a list of dimension records that have changed since 01 December 2018.  The page size is 500 and the first page is returned

https://demo.assetic.net/api/v2/dimensions?requestParams.filters=LastModified~gt~'2018-12-01T00:00:00'~and~AssetCategory~eq~'Roads'&requestParams.page=1&requestParams.pageSize=500

 

GET /api/v2/functionallocations/{id} and GET /api/v2/functionallocation

The API GET /api/v2/functionallocations/{id} requires either the user-friendly Functional Location ID string or the internal assetic GUID for the functional location as the {id}

GET /api/v2/servicecriteria/score and GET /api/v2/servicecriteria/score/{id}

Service Criteria are scores or ratings of an asset component.  For each type of component, there may be one or more types of Service Criteria.  The most recent Service Criteria score is flagged as the current score, however, all prior scores may also be retrieved via the Assetic REST API endpoint:

GET /api/v2/servicecriteria/score. 

The Assetic REST API endpoint GET /api/v2/servicecriteria/score/{id} retrieves a service criteria record where the Id is the unique integer assessment id.  The Id may be obtained from the Advanced Search as the field "ID" (module="Assessments", Category="Service Criteria").

If the Id is unknown, the endpoint GET /api/v2/servicecriteria/score may be used with a search filter to get a list of service criteria.  The list of searchable fields for service criteria is defined in the article Asset Integration Overview.

Get the Service Criteria for record Id = 345

GET /api/v2/servicecriteria/score/345

Get the current Service Criteria for asset "5101901".  This will return the current Service Criteria scores for the components of that asset, for all Service Criteria Types.  Since it is a paginated search, page 1 is specified,  and 25 records per page are specified:

GET /api/v2/servicecriteria/score?requestParams.filters=IsMostRecentScore~eq~'True'~and~AssetId~eq~'5101901'&requestParams.page=1&requestParams.pageSize=25